SplunkのAdd-on Builderで自前のアドオンを作成してみる（REST API編）
オペレーション部 江口です。
Splunkでデータ入力を行うためのアドオンの作成を助けてくれるツール、Add-on Builderについてご紹介したいと思います。
Splunkアドオンとは
Splunkは、任意のダッシュボードや機能拡張を行うアプリケーション（Splunk App）をユーザがインストールできます（自前で開発もできます）。 そのAppの一種で、任意のデータを入力する機能を拡張するものを「アドオン」と言っています。 スクリプト（シェルスクリプトやPython）を実行し、任意のAPIを実行してデータを取得したり、任意に加工するなどの処理を行ってSplunkに渡す処理を行えます。
Splunk Add-on Builderとは
このSplunkアドオンの開発を助けてくれるツールがSplunk Add-on Builderです。これ自体がSplunkにインストールするアプリとして提供されていて、Splunkbaseで入手できます。
https://splunkbase.splunk.com/app/2962/
詳しい使い方については、Splunkの公式ドキュメントで詳しく説明されています。
https://docs.splunk.com/Documentation/AddonBuilder/latest/UserGuide/Overview
開発を助けるいろいろな機能が利用できるのですが、この記事ではとりあえず一番簡単なREST APIでデータを入力するアドオンの作成を通じて、Addーon Builderの基本的な使い方をご紹介します。
この記事で作成するアドオン
REST APIと書きましたが、実際のところURLを叩いて実行結果としてJSONが返ってくるならば指摘できると思われます。 ということで、この記事では、AWSのサービスの状態をJSONで取得する下記のURLを試しに使ってみたいと思います。（手軽に思われたので）
https://status.aws.amazon.com/data.json
ちなみに実行時に返ってくるJSONデータは以下のようなものです。
{
"archive":[
{
"service_name":"Auto Scaling (N. Virginia)",
"summary":"[RESOLVED] Increased API Error Rates",
"date":"1525914401",
"status":1,
"details":"",
"description":"<div><span class="yellowfg"> 6:06 PM PDT</span> We are investigating increased API error rates in the US-EAST-1 Region.</div><div><span class="yellowfg"> 6:26 PM PDT</span> We are continuing to investigate increased API error rates in the US-EAST-1 Region</div><div><span class="yellowfg"> 7:24 PM PDT</span> We have identified the root cause of the elevated API error rates and can confirm that most customers have recovered. We are continuing to work towards full resolution.</div><div><span class="yellowfg"> 7:40 PM PDT</span> Between 5:42 PM and 7:04 PM PDT, we experienced increased API error rates in the US-EAST-1 Region. The issue has been resolved and the service is operating normally.</div>",
"service":"autoscaling-us-east-1"
},
(略)
"current":[
]
}
archiveに過去の障害の情報が、currentには現行の障害の情報が入ってきます。アドオンを作成すると、このJSONデータをSplunkに取り込ませることができるようになります。
Add-on Builderのインストール
まずはAdd-on Builderのインストールですが、前述のようにSplunk Appの一種ですので、他のAppと方法は変わりません。
Splunkの「Appの管理」-「Browse more apps」から「Add-on Builder」で検索して見つけるか、もしくはSplunkbaseのAppページからファイルとしてダウンロードし「Install app from file」からインストールを行います。
インストールすると、アプリケーションのメニューに「Splunk Addーon Builder」が追加されますので、クリックしてメインメニューへと移動してみましょう。
アドオンの作成
新しいアドオンを作るには、Addーon Builderのメインメニューから「New Add-on」をクリックします。
名前やバージョンなど、アドオンの基本情報の入力画面が表示されます。
内部的には、ここに設定した名前を使ってこのアドオンのアプリケーション用ディレクトリが作成されます。具体的なパスは$SPLUNK_HOME/etc/apps/TA-アドオン名です。
データ入力の設定
登録すると、そのアドオンの設定画面に遷移します。
画面から「Configure Data Collection」をクリックすると、データ入力方法の画面に遷移します。
データ入力の種類は3種類から選択可能です。
- REST API
- Shell Commands
- Python code
「REST API」はすでに説明したように、URLを指定してREST APIを叩き、その実行結果をSplunkに保存します。 「Shell Commands」「Python code」はそれぞれシェルコマンド、Pythonスクリプトの実行結果をSplunkに保存します。 単純にREST APIの実行結果を保存できれば良いのであれば「REST API」を、サーバ内でシェルで取得できる範囲の情報であれば「Shell Commands」を、複雑な処理が必要であれば「Python code」を使う、といった使い分けになるかと思います。ここでは「REST API」を選択して進めます。
プロパティ、パラメータの指定
入力方法を指定すると、プロパティ、パラメータの指定画面に遷移します。この画面には3つのタブがあります。
- Data Input Properties
- Data Input Parameters
- Add-on Setup Parameters
「Data Input Properties」は入力したデータのソースタイプの指定や、データを取得する間隔などの値を指定します。
「Data Input Parameters」は、ユーザに入力してもらう任意のパラメータを指定する画面で、入力フォームを作成することができます。ここで定義したパラメータのセットは、ユーザ側では複数定義が可能です。
「Add-on Setup Parameters」は、「Data Input Parameters」と似ていますが、アドオン全体のグローバルな設定の入力フォームを作成できます。「Data Input Parameters」はユーザが複数の定義を作成であるのに対して、こちらはグローバルな設定のため定義は1つのみ、という点が異なります。プリセットとして、プロキシサーバの設定、グローバルアカウント設定が用意されています。
「Data Input Parameters」「Add-on Setup Parameters」は有用な設定ですが、この記事では非常に単純なURLを指定するため特に利用せず、「Data Input Properties」に基本的な情報のみ入力しました。
REST API設定
次の画面では、具体的なREST APIの情報を指定します。URL、メソッド、パラメータ、ヘッダ等です。
今回は、「REST URL」にhttps://status.aws.amazon.com/data.json、メソッドに「GET」を指定しました。
設定後、「テスト」をクリックすると、指定URLへのアクセスが試行され、無事情報が取得できれば結果が「Output」欄に表示されます。
設定にはURL、メソッドなどのREST APIへアクセスするための項目のほか、「Event extraction settings」という抽出のための設定があります。ここではイベントの受け取ったJSONデータのどの部分を取得するか、を「JSON path」という項目で指定できます（指定しなければ、JSONデータすべてが一つのイベントとして記録されます）。
このJSON pathの書式は公式ドキュメントの下記ページに掲載されています。
たとえば、JSONデータのルート直下「current」フィールド下の各エントリのみを抽出したい場合は、$.current.[*]と記述します。$がルートを表し、固定のフィールド名は.フィールド名と指定。.[*]を記述することで、指定フィールド下の各配列を取得することができます。0番目の値を指定して取得したい場合は[0]などと直接指定します。サービスのステータスとしては、現在問題が起こっている情報のみ取得できれば良いと考え、ここでは$.current.[*]を指定してみました。
保存
指定や抽出に問題がなければ、「完了」を押すと入力の設定が保存されます。設定の適用には一度Splunkプロセスの再起動が必要となります。
作成したアドオンの利用とエクスポート
Splunkを再起動すると、前章で作成したデータ入力が有効になり、「Data Input Properties」で定義した間隔で情報を取得、Splunkにイベントを保存していきます。
サーチでイベント情報を確認してみると、以下のようにきちんと情報が表示されました。
また、作成したアドオンがAppとしてメニュー上に表示されるようになります。
Add-on Builderのメニュー画面では、アドオンのエクスポートも可能になっています。アプリの情報の下のメニューから「エクスポート」をクリックすると、tgz形式でアドオンがダウンロードできます。ダウンロードしたアドオンは、「Appの管理」メニューの「Install app from file」から他のSplunkでインストールができるようになります。
Splunkbaseでパブリックに配布するには、隣のメニューにある「Validate & Package」で問題ないかを検証・パッケージングする必要がありますが、このエクスポートでとりあえず社内などローカルに展開することはできるようになりました。
終わりに
以上、ざっとSplunk Add-on Builderでの簡単なアドオンの作成例を紹介しました。複雑な処理が必要な場合はPythonスクリプトを記述する必要があり、その場合はこれよりは若干手間がかかります。そちらも別の記事でいずれ紹介したいと思います。ともあれ、このツールを利用するとSplunkのアドオンが比較的楽に作成できる、という点が理解いただけたならうれしいです。
